internmap

What is internmap?

The internmap npm package provides data structures for interned collections, which are collections that store a single copy of each unique value. This can be useful for memory efficiency and performance when dealing with large datasets with many repeated values. The package includes implementations of maps and sets that use interned keys.

What are internmap's main functionalities?

InternMap

InternMap is a map data structure that automatically interns its keys, ensuring that each key is stored only once in memory, even if it is set multiple times with different values.

{"const InternMap = require('internmap');
const map = new InternMap();
map.set('a', 1);
map.set('b', 2);
console.log(map.get('a')); // 1
console.log(map.has('b')); // true
console.log(map.size); // 2"}

InternSet

InternSet is a set data structure that automatically interns its values, ensuring that each value is stored only once in memory, even if it is added multiple times.

{"const InternSet = require('internmap').InternSet;
const set = new InternSet();
set.add('a');
set.add('b');
set.add('a');
console.log(set.has('a')); // true
console.log(set.size); // 2"}

Other packages similar to internmap

d3-array

The d3-array package provides a similar functionality with its InternSet and InternMap, which are used for efficient data manipulation and analysis in D3.js visualizations. It is similar to internmap but is part of the larger D3.js ecosystem.

es6-weak-map

The es6-weak-map package provides a polyfill for the ES6 WeakMap, which is a collection of key/value pairs with weakly held keys. While it does not intern keys, it provides a way to associate data with objects without preventing garbage collection, which can be useful for memory management.

immutable

The immutable package offers Map, Set, and other collection types with persistent immutable data structures. These structures can improve performance and memory usage by sharing structure between different versions, which is a different approach to efficiency compared to internmap's interning of keys.

README

InternMap

For live examples, see https://observablehq.com/@mbostock/internmap.

If you use dates as keys in a JavaScript Map (or as values in a Set), you may be surprised that it won’t work as you expect.

dateMap = new Map([
  [new Date(Date.UTC(2001, 0, 1)), "red"],
  [new Date(Date.UTC(2001, 0, 1)), "green"] // distinct key!
])

dateMap.get(new Date(Date.UTC(2001, 0, 1))) // undefined!

That’s because Map uses the SameValueZero algorithm to determine key equality: for two dates to be considered the same, they must be the same instance (the same object), not just the same moment in time. This is true of the equality operator, too.

{
  const date1 = new Date(Date.UTC(2001, 0, 1));
  const date2 = new Date(Date.UTC(2001, 0, 1));
  return date1 === date2; // false!
}

You can avoid this issue by using primitive values such as numbers or strings as keys instead. But it’s tedious and easy to forget to coerce types. (You’ll also need to do the inverse type conversion when pulling keys out of the map, say when using map.keys or map.entries, or when iterating over the map. The inverse above is new Date(key). Also, if you forget to coerce your key to a number when using map.get, it’s easy not to notice because the map won’t throw an error; it’ll simply return undefined.)

numberMap = new Map([[978307200000, "red"]])
numberMap.get(978307200000) // "red"
numberMap.get(new Date(978307200000)) // undefined; oops!

Wouldn’t it be easier if Map and Set “just worked” with dates? Or with any object that supports object.valueOf?

Enter InternMap. Interning refers to storing only one copy of each distinct key. An InternMap considers two Date instances representing the same moment to be equal, storing only the first instance.

map = new InternMap([
  [new Date(Date.UTC(2001, 0, 1)), "red"],
  [new Date(Date.UTC(2001, 0, 1)), "green"] // replaces previous entry
])

map.get(new Date(Date.UTC(2001, 0, 1))) // "green"

[...map.keys()] // [2001-01-01]

InternMap extends Map, so you can simply drop it in whenever you’d prefer this behavior to the SameValueZero algorithm. Because InternMap calls object.valueOf only for non-primitive keys, note that you can pass primitive keys, too.

map.get(978307200000) // "green"; this works too!

InternMap keeps only the first distinct key according to its associated primitive value. Avoid adding keys to the map with inconsistent types.

map2 = new InternMap([
  [978307200000, "red"], // danger!
  [new Date(Date.UTC(2001, 0, 1)), "blue"]
])

map2.get(new Date(Date.UTC(2001, 0, 1))) // "blue"; this still works…

[...map2.keys()] // [978307200000]; but the key isn’t a Date

While InternMap uses object.valueOf by default to compute the intern key, you can pass a key function as a second argument to the constructor to change the behavior. For example, if you use JSON.stringify, you can use arrays as compound keys (assuming that the array elements can be serialized to JSON).

map3 = new InternMap([
  [["foo", "bar"], 1],
  [["foo", "baz"], 2],
  [["goo", "bee"], 3]
], JSON.stringify)

map3.get(["foo", "baz"]) // 2

There’s an InternSet class, too.

set = new InternSet([
  new Date(Date.UTC(2000, 0, 1)),
  new Date(Date.UTC(2001, 0, 1)),
  new Date(Date.UTC(2001, 0, 1))
])